org.globalplatform.contactless
Class GPCLSystem

java.lang.Object
  org.globalplatform.contactless.GPCLSystem

public class GPCLSystem
extends java.lang.Object

The GPCLSystem class exposes a subset of the behavior of the CRS (OPEN extension) to other on-card components. The class is composed of static methods visible to all applets importing the org.globalplatform.contactless package. Static methods are provided to:

• Retrieve Contactless Registry Objects
• Configure access to ISO 14443 interface
• Set Volatile Priority
• Retrieve the OPEN's Default and Current Protocol Parameters
  • Default Protocol Parameter,
  • Current Protocol Parameters,

Field Summary

static short	AFI_ANY Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for all Contactless applications that belong to any family
static short	AFI_DATA_STORAGE Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Data Storage family
static short	AFI_FINANCIAL Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Financial family
static short	AFI_GAMING Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Gaming family
static short	AFI_IDENTIFICATION Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Identification family
static short	AFI_MEDICAL Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Medical family
static short	AFI_MULTIMEDIA Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Multimedia family
static short	AFI_TELECOMMUNICATION Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Telecommunication family
static short	AFI_TRANSPORT Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Transport family
static short	CARD_INFO_COUNTER_UPDATE The Card GPCLentry update counter.
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A The requested information is the CURRENT_PROTOCOL_DATA_TYPE_A.
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B The requested information is the CURRENT_PROTOCOL_DATA_TYPE_B.
static short	CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F The requested information is the CURRENT_PROTOCOL_DATA_TYPE_F.
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_A.
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_B.
static short	CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_F.
static byte	GPCL_CL_APPLICATION The OPEN uses this identifier to retrieve the CLApplet interface implemented by an applet.
static byte	GPCL_CREL_APPLICATION The OPEN uses this identifier to retrieve the CRELApplication interface implemented by an applet.
static byte	GPCL_CRS_APPLICATION The OPEN uses this identifier to retrieve the CRSApplication interface implemented by an applet.
static short	GPCL_INTERFACE_ISO14443 This constant is used with setCommunicationInterface(short, boolean) to manage a ISO14443 based communication interface.

Method Summary

static short	getCardCLInfo(byte[] buffer, short offset, short info) Retrieve the OPEN's conctactless parameters.
static GPCLRegistryEntry	getGPCLRegistryEntry(javacard.framework.AID oAID) Gets a reference to a GPCLRegistryEntry interface.
static GPCLRegistryEntry	getNextGPCLRegistryEntry(GPCLRegistryEntry oEntry, short sFamily) Looks up contactless applets belonging to a particular application family.
static void	setCommunicationInterface(short sInterface, boolean onOff) This method allows switching ON or switching OFF the ISO 14443 interface at GlobalPlatform card level.
static void	setVolatilePriority(GPCLRegistryEntry oEntry) Sets up or discards the volatile priority.

Methods inherited from class java.lang.Object

equals

Field Detail

GPCL_CL_APPLICATION

public static final byte GPCL_CL_APPLICATION

The OPEN uses this identifier to retrieve the CLApplet interface implemented by an applet.

See Also:

Constant Field Values

GPCL_CRS_APPLICATION

public static final byte GPCL_CRS_APPLICATION

The OPEN uses this identifier to retrieve the CRSApplication interface implemented by an applet.

See Also:

Constant Field Values

GPCL_CREL_APPLICATION

public static final byte GPCL_CREL_APPLICATION

The OPEN uses this identifier to retrieve the CRELApplication interface implemented by an applet.

See Also:

Constant Field Values

AFI_ANY

public static final short AFI_ANY

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for all Contactless applications that belong to any family

See Also:

Constant Field Values

AFI_TRANSPORT

public static final short AFI_TRANSPORT

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Transport family

See Also:

Constant Field Values

AFI_FINANCIAL

public static final short AFI_FINANCIAL

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Financial family

See Also:

Constant Field Values

AFI_IDENTIFICATION

public static final short AFI_IDENTIFICATION

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Identification family

See Also:

Constant Field Values

AFI_TELECOMMUNICATION

public static final short AFI_TELECOMMUNICATION

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Telecommunication family

See Also:

Constant Field Values

AFI_MEDICAL

public static final short AFI_MEDICAL

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Medical family

See Also:

Constant Field Values

AFI_MULTIMEDIA

public static final short AFI_MULTIMEDIA

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Multimedia family

See Also:

Constant Field Values

AFI_GAMING

public static final short AFI_GAMING

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Gaming family

See Also:

Constant Field Values

AFI_DATA_STORAGE

public static final short AFI_DATA_STORAGE

Constant to use with getNextGPCLRegistryEntry(GPCLRegistryEntry, short) to look for applications that belong to the Data Storage family

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_A

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_A.

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_B

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_B.

See Also:

Constant Field Values

CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F

public static final short CARD_INFO_DEFAULT_PROTOCOL_DATA_TYPE_F

The requested information is the DEFAULT_PROTOCOL_DATA_TYPE_F.

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_A

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_A.

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_B

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_B.

See Also:

Constant Field Values

CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F

public static final short CARD_INFO_CURRENT_PROTOCOL_DATA_TYPE_F

The requested information is the CURRENT_PROTOCOL_DATA_TYPE_F.

See Also:

Constant Field Values

CARD_INFO_COUNTER_UPDATE

public static final short CARD_INFO_COUNTER_UPDATE

The Card GPCLentry update counter. Each time a GPCLRegistryEntry information is updated this counter is incremented. Used to synchronize the CRS/CREL application list.

See Also:

Constant Field Values

GPCL_INTERFACE_ISO14443

public static final short GPCL_INTERFACE_ISO14443

This constant is used with setCommunicationInterface(short, boolean) to manage a ISO14443 based communication interface.

See Also:

Constant Field Values

Method Detail

getGPCLRegistryEntry

public static GPCLRegistryEntry getGPCLRegistryEntry(javacard.framework.AID oAID)

Gets a reference to a GPCLRegistryEntry interface. If no AID is input (i.e. entry is null), this method provides the GPCLRegistryEntry of the requesting applet.

Contactless applets are those applets that have access to the contactless interface.

Parameters:

oAIDidentifies - the applet for which the GPCLRegistryEntry interface should be retrieved, or null.

Returns:

the GPCLRegistryEntry interface object, or null

if there is no applet with the specified entry or,

if the caller

• has not GLOBAL_REGISTRY privilege, and
• is not the Security Domain directly or indirectly associated with the applet being investigated, and
• is not the investigated applet itself, and
• is a not CREL Application registered in the investigated applet's CREL list

getNextGPCLRegistryEntry

public static GPCLRegistryEntry getNextGPCLRegistryEntry(GPCLRegistryEntry oEntry,
                                                         short sFamily)

Looks up contactless applets belonging to a particular application family. The OPEN maintains an internal list of contactless applets. This method returns the GPCLRegistryEntry object for the next contactless applet that matches the search criteria.

Contactless applets are those applets that have access to the contactless interface.

• Application with GLOBAL_REGISTRY privilege can iterate over all application
• A CREL Application can only iterate over its referencing Applications.
• Security Domain can only iterate on its directly or indirectly associated Application(s) unless it has the GLOBAL_REGISTRY privilege.

Parameters:

oEntry -

• if oEntry is null, this method returns the first Entry matching the specified family.
• If the list is empty, the method shall return null.
• If oEntry is not null, and represents an application matching the specified family, this method retrieves the next application matching the specified family, otherwise it shall return null.
• If oEntry points to the last application matching the specified family, the method shall return null.

sFamily - the Family Identifier to look for.

Returns:

the reference to the GPCLRegistryEntry interface object of the contactless applet matching the search criteria; null is returned if no application is matching or the end of the list is reached.

Throws:

ISOException - with reason

• ISO7816.SW_CONDITIONS_NOT_SATISFIED if
  • the caller has not GLOBAL_REGISTRY privilege, and
  • the caller is not a Security Domain or is a Security Domain but the oEntry is not directly or indirectly associated with this Security Domain, and
  • the caller is not a CREL Application, or is a CRELApplication but the oEntry is not referencing this CREL Application.

See Also:

AFI_ANY, AFI_TRANSPORT, AFI_TELECOMMUNICATION, AFI_MULTIMEDIA, AFI_MEDICAL, AFI_IDENTIFICATION, AFI_GAMING, AFI_FINANCIAL, AFI_DATA_STORAGE

setVolatilePriority

public static void setVolatilePriority(GPCLRegistryEntry oEntry)

Sets up or discards the volatile priority.

Parameters:

oEntry -

• null value discards the volatile priority
• The GPCLRegistryEntry to set in the volatile priority If the GPCLentry identifies a Head of a group all applications of this group are part of the volatile priority in the same order as in the GlobalPlatform registry.

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_STATISFIED if the caller has not GPCLRegistryEntry.PRIVILEGE_CONTACTLESS_ACTIVATION

getCardCLInfo

public static short getCardCLInfo(byte[] buffer,
                                  short offset,
                                  short info)

Retrieve the OPEN's conctactless parameters.

Parameters:

buffer - where requested information shall be written

offset - within buffer, where requested information shall be written

info - any CARD_INFO_XX constant.

Returns:

(offset + length of data written in buffer)

Throws:

ArrayIndexOutOfBoundsException - if storing the Application Information bytes would cause access outside array bounds or the offset is negative.

NullPointerException - if buffer is null

setCommunicationInterface

public static void setCommunicationInterface(short sInterface,
                                             boolean onOff)

This method allows switching ON or switching OFF the ISO 14443 interface at GlobalPlatform card level. The technical implementation for switching an interface is configuration dependent.

Parameters:

sInterface - the interface identifier: GPCL_INTERFACE_ISO14443.

onOff - true to switch ON, false to switch OFF

Throws:

ISOException - with reason

• ISO7816.SW_CONDITION_NOT_STATISFIED if the caller has not GPCLRegistryEntry.PRIVILEGE_CONTACTLESS_ACTIVATION when managing the GPCL_INTERFACE_ISO14443
• ISO7816.SW_WRONG_DATAif sInterface identifier does not exist.